standardized-audio-context

What is standardized-audio-context?

The standardized-audio-context npm package provides a standardized way to work with the Web Audio API across different browsers. It aims to offer a consistent and reliable interface for audio processing and synthesis, making it easier to create complex audio applications.

What are standardized-audio-context's main functionalities?

Creating an Audio Context

This code initializes a new AudioContext, which is the primary interface for managing and playing audio in a web application.

const audioContext = new AudioContext();

Loading and Playing Audio

This code demonstrates how to load an audio file, decode it, and play it using the AudioContext.

const audioContext = new AudioContext();
fetch('path/to/audio/file.mp3')
  .then(response => response.arrayBuffer())
  .then(arrayBuffer => audioContext.decodeAudioData(arrayBuffer))
  .then(audioBuffer => {
    const source = audioContext.createBufferSource();
    source.buffer = audioBuffer;
    source.connect(audioContext.destination);
    source.start();
  });

Creating and Connecting Audio Nodes

This code shows how to create an oscillator node and a gain node, connect them, and start the oscillator to produce sound.

const audioContext = new AudioContext();
const oscillator = audioContext.createOscillator();
const gainNode = audioContext.createGain();
oscillator.connect(gainNode);
gainNode.connect(audioContext.destination);
oscillator.start();

Applying Audio Effects

This code demonstrates how to apply a biquad filter effect to an audio signal by connecting an oscillator node to a gain node, then to a biquad filter node, and finally to the audio context's destination.

const audioContext = new AudioContext();
const oscillator = audioContext.createOscillator();
const gainNode = audioContext.createGain();
const biquadFilter = audioContext.createBiquadFilter();
oscillator.connect(gainNode);
gainNode.connect(biquadFilter);
biquadFilter.connect(audioContext.destination);
oscillator.start();

Other packages similar to standardized-audio-context

tone

Tone.js is a framework for creating interactive music in the browser. It provides a higher-level API on top of the Web Audio API, making it easier to create complex audio applications. Compared to standardized-audio-context, Tone.js offers more features for music production, such as built-in instruments, effects, and scheduling capabilities.

howler

Howler.js is a JavaScript audio library for the modern web. It simplifies audio playback and provides a consistent API across different browsers. While standardized-audio-context focuses on providing a standardized interface for the Web Audio API, Howler.js is more geared towards simplifying audio playback and management, making it easier to work with audio files and streams.

pizzicato

Pizzicato.js is a library that aims to simplify the creation and manipulation of sounds in the browser. It provides an easy-to-use API for common audio tasks such as playing sounds, applying effects, and creating sound loops. Compared to standardized-audio-context, Pizzicato.js offers a more user-friendly interface for basic audio tasks, but may not provide the same level of control and flexibility for advanced audio processing.

README

standardized-audio-context

A cross-browser implementation of the AudioContext which aims to closely follow the standard.

This package provides a subset of the Web Audio API which works in a reliable and consistent way in every supported browser. In contrast to other popular polyfills standardized-audio-context does not patch or modify anything on the global scope. In other words, it does not cause any side effects. It can therefore be used safely inside of libraries.

One of the goals of standardized-audio-context is to only polyfill missing functionality and to avoid rewriting builtin features whenever possible.

There are of course some things which cannot be faked in a way that makes them as performant as they could be when implemented natively. The most obvious amongst those things is the AudioWorklet. Please have a look at the list of all supported methods below for more detailed information.

Usage

The standardized-audio-context is available on npm and can be installed as usual.

npm install standardized-audio-context

You can then import the AudioContext and OfflineAudioContext like this:

import { AudioContext, OfflineAudioContext } from 'standardized-audio-context';

Afterwards the AudioContext/OfflineAudioContext can be used in the same way as their native counterparts. The following snippet will produce a nice and clean sine wave.

import { AudioContext } from 'standardized-audio-context';

const audioContext = new AudioContext();
const oscillatorNode = audioContext.createOscillator();

oscillatorNode.connect(audioContext.destination);

oscillatorNode.start();

An alternative approach would be to use the AudioNode constructors (the OscillatorNode constructor in this case) instead of the factory methods.

import { AudioContext, OscillatorNode } from 'standardized-audio-context';

const audioContext = new AudioContext();
const oscillatorNode = new OscillatorNode(audioContext);

oscillatorNode.connect(audioContext.destination);

oscillatorNode.start();

API

AudioContext

This is an incomplete implementation of the AudioContext interface. It misses the following factory methods: createConvolver(), createDelay(), createDynamicsCompressor(), createMediaStreamDestination(), createPanner(), createPeriodicWave(), createScriptProcessor(), createStereoPanner() and createWaveShaper(). The listener property is also missing for now.

With the exception of createMediaStreamDestination() and createScriptProcessor() there is no technical reason for not supporting these methods. They are just not implemented yet. Please create a new issue if you desperately need any of them.

OfflineAudioContext

This is an incomplete implementation of the OfflineAudioContext interface. It misses mostly the same methods as the AudioContext which are: createConvolver(), createDelay(), createDynamicsCompressor(), createPanner(), createPeriodicWave(), createScriptProcessor(), createStereoPanner() and createWaveShaper().

audioWorklet

The AudioWorklet is accessible as a property of an AudioContext or OfflineAudioContext. It uses the ScriptProcessorNode internally to create an AudioWorkletProcessor in any browser but Chrome. This means it will not provide the performance improvements that you would normally expect from using an AudioWorklet.

The fact that the internal implementation relies on a ScriptProcessorNode also implies that the channelCountMode can only be 'explicit' for now. It also means that the total number of channels of all inputs plus the number of all parameters can't be larger than six.

Another thing to keep in mind is that the fallback will evaluate the AudioWorkletProcessor on the global scope. It gets isolated in basic way to mimic the AudioWorkletGlobalScope but that can't be done in a way which makes it impossible for an attacker to break out of that sandbox. This should not be a problem unless you load an AudioWorklet from an untrusted source.

decodeAudioData()

This is an implementation of the decodeAudioData() method.

AnalyserNode / createAnalyser()

This is an implementation of the AnalyserNode constructor and the createAnalyser() factory method respectively.

BiquadFilterNode / createBiquadFilter()

This is an implementation of the BiquadFilterNode constructor and the createBiquadFilter() factory method respectively.

AudioBuffer / createBuffer()

This is an implementation of the AudioBuffer constructor and the createBuffer() factory method respectively.

AudioBufferSourceNode / createBufferSource()

This is an implementation of the AudioBufferSourceNode constructor and the createBufferSource() factory method respectively. It is currently missing the detune AudioParam.

ChannelMergerNode / createChannelMerger()

This is an implementation of the ChannelMergerNode constructor and the createChannelMerger() factory method respectively.

ChannelSplitterNode / createChannelSplitter()

This is an implementation of the ChannelSplitterNode constructor and the createChannelSplitter() factory method respectively.

ConstantSourceNode / createConstantSource()

This is an implementation of the ConstantSourceNode constructor and the createConstantSource() factory method respectively.

GainNode / createGain()

This is an implementation of the GainNode constructor and the createGain() factory method respectively.

IIRFilterNode / createIIRFilter()

This is an implementation of the IIRFilterNode constructor and the createIIRFilter() factory method respectively. It has to be faked internally with a ScriptProcessorNode in Safari which means it is not as performant as in other browsers which support it natively.

MediaElementAudioSourceNode / createMediaElementSource()

This is an implementation of the MediaElementAudioSourceNode constructor and the createMediaElementSource() factory method respectively. It does only work with an AudioContext but not with an OfflineAudioContext.

MediaStreamSourceNode / createMediaStreamSource()

This is an implementation of the MediaStreamAudioSourceNode constructor and the createMediaStreamSource() factory method respectively. It does only work with an AudioContext but not with an OfflineAudioContext.

OscillatorNode / createOscillator()

This is an implementation of the OscillatorNode constructor and the createOscillator() factory method respectively.

isSupported()

standardized-audio-context is also exporting a promise which can be accessed by calling isSupported(). This promise resolves to a boolean which indicates if the functionality is supported within the currently used browser. This is not part of the specification.

import { isSupported } from 'standardized-audio-context';

isSupported()
    .then((isSupported) => {
        if (isSupported) {
            // yeah everything should work
        } else {
            // oh no this browser seems to be outdated
        }
    });

TypeScript

This package is written in TypeScript which means it can be used seamlessly in any TypeScript project. But that is entirely optional.

In contrast to the Web Audio API types that TypeScript provides out of the box the types exported by standardized-audio-context do actually match the concrete implementation. TypeScript generates its types from the Web IDL definition of the Web Audio API which does not always match the actually available implementations.

Tests

All implemented methods are covered by a large number of tests which are executed on a variety of browsers. Many thanks to BrowserStack and Sauce Labs for allowing this module to be tested with their services.